/*
 * Copyright 2002-2019 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.transaction.interceptor;

import java.util.Collection;

import org.springframework.lang.Nullable;
import org.springframework.transaction.TransactionDefinition;

/**
 * This interface adds a {@code rollbackOn} specification to {@link TransactionDefinition}.
 * As custom {@code rollbackOn} is only possible with AOP, it resides in the AOP-related
 * transaction subpackage.
 *
 * @author Rod Johnson
 * @author Juergen Hoeller
 * @author Mark Paluch
 * @since 16.03.2003
 * @see DefaultTransactionAttribute
 * @see RuleBasedTransactionAttribute
 */
/*
1. 总结
TransactionAttribute 是Spring事务框架中用于定义事务属性的接口
它继承自 TransactionDefinition，扩展了事务配置功能
主要用于声明式事务管理，支持通过AOP实现复杂的回滚规则
2. 内部成员说明
方法定义
getQualifier(): 获取与事务属性关联的限定符值，用于选择对应的事务管理器处理特定事务
getLabels(): 获取与事务属性关联的标签集合，可用于应用特定事务行为或描述性用途
rollbackOn(Throwable ex): 判断是否应该对给定异常执行回滚操作，是自定义回滚规则的核心方法
3. 类关系结构
TransactionDefinition (interface)
└── TransactionAttribute (interface)
    ├── DefaultTransactionAttribute (class)
    │   └── RuleBasedTransactionAttribute (class)
    └── DelegatingTransactionAttribute (class)
与其他相关类的区别：
	TransactionDefinition: 事务属性的通用接口，定义基本事务特性（用于声明式事务管理，支持复杂的回滚规则和事务选择逻辑）
	TransactionAttribute: 在 TransactionDefinition 基础上扩展，支持AOP特有的回滚规则和限定符功能（用于声明式事务管理，支持复杂的回滚规则和事务选择逻辑）
	DefaultTransactionAttribute: 默认的事务属性实现，提供了基本的事务配置
	RuleBasedTransactionAttribute: 基于规则的事务属性实现，支持复杂的事务配置逻辑
	DelegatingTransactionAttribute: 委托模式的事务属性实现，支持事务属性的代理和链式处理
4. 使用场景
	需要自定义回滚规则的声明式事务管理
	多个事务管理器共存时，需要根据限定符选择特定事务管理器
	需要为事务添加标签以支持特定业务逻辑或监控需求
	实现复杂的事务配置逻辑，如基于条件的事务传播行为
	与AOP结合使用，实现细粒度的事务控制


5. 实际代码应用示例
@Service
public class UserService {

    @Autowired
    private PlatformTransactionManager transactionManager;

    // 自定义回滚规则的事务方法
    @Transactional(
        rollbackFor = {UserNotFoundException.class, InvalidUserException.class},
        noRollbackFor = {UserAlreadyExistsException.class}
    )
    public void createUser(User user) {
        // 创建用户逻辑
        if (user.getId() == null) {
            throw new UserNotFoundException("用户不存在");
        }

        // 其他业务逻辑...
    }

    // 使用TransactionTemplate实现编程式事务
    @Autowired
    private TransactionTemplate transactionTemplate;

    public void updateUser(Long userId, String newName) {
        // 设置自定义事务属性
        DefaultTransactionAttribute attr = new DefaultTransactionAttribute();
        attr.setPropagationBehavior(TransactionDefinition.PROPAGATION_REQUIRED);
        attr.setIsolationLevel(TransactionDefinition.ISOLATION_READ_COMMITTED);

        // 设置自定义回滚规则
        attr.setRollbackOn(new Class<?>[]{UserNotFoundException.class});

        // 执行事务
        transactionTemplate.execute(new TransactionCallbackWithoutResult() {
            @Override
            protected void doInTransactionWithoutResult(TransactionStatus status) {
                // 更新用户逻辑
                try {
                    // 执行业务逻辑
                } catch (UserNotFoundException e) {
                    // 根据自定义规则触发回滚
                    status.setRollbackOnly();
                }
            }
        });
    }
}

 */
public interface TransactionAttribute extends TransactionDefinition {

	/**
	 * Return a qualifier value associated with this transaction attribute.
	 * <p>This may be used for choosing a corresponding transaction manager
	 * to process this specific transaction.
	 * @since 3.0
	 */
	@Nullable
	String getQualifier();

	/**
	 * Return labels associated with this transaction attribute.
	 * <p>This may be used for applying specific transactional behavior
	 * or follow a purely descriptive nature.
	 * @since 5.3
	 */
	Collection<String> getLabels();

	/**
	 * Should we roll back on the given exception?
	 * @param ex the exception to evaluate
	 * @return whether to perform a rollback or not
	 */
	boolean rollbackOn(Throwable ex);

}
